Fix the following code review findings on aictrl-dev/cli PR #87 (head branch).
Run the relevant tests/linters after each change.

1. packages/cli/src/cli/cmd/run.ts:488-494 — limit:0 yields Infinity ratio, breaks null contract
   Detail: The guard `contextLimit != null` does not catch the case where the model's context limit is `0`. `Provider.Model.limit.context` is a required `z.number()` (provider.ts:703), and config-defined custom models without a limit default `context` to `0` (provider.ts:929: `context: model.limit?.context ?? existingModel?.limit?.context ?? 0`). For such models `Provider.getModel` succeeds and returns `context: 0`, so `contextLimit` is `0` (not `null`), the guard passes, and `ratio = contextUsed / 0` evaluates to `Infinity` (or `NaN` when `contextUsed` is also `0`). `JSON.stringify` then serializes `Infinity`/`NaN` as `null` *inside* the context object, yielding `{ used: <N>, limit: 0, ratio: null }` instead of the documented top-level `null`. EVENTS.md explicitly promises: "null — emitted when the model's context limit is not known (e.g. unregistered custom endpoint)". This diverges from the documented contract and emits a misleading object for the exact scenario it claims to handle. Fix: also require `contextLimit > 0` before emitting the object.
   Suggested fix: Change the guard from `contextLimit != null` to `contextLimit != null && contextLimit > 0` so a context limit of `0` (config/custom models without a known limit) is treated as "unknown" and emits `null` as documented, avoiding `Infinity`/`NaN` in the ratio.
2. packages/cli/test/cli/usage-token-breakdown.test.ts:63 — Tests grep source text instead of running emit path
   Detail: The new tests assert behavior by reading `run.ts` as a string and matching regexes against the source text rather than exercising the emit path. Several assertions are loose enough to pass even if the logic is wrong:\n\n- `test("context.ratio is used / limit")` (line 63) uses `/ratio.*\\/|\\/.*ratio|used\\s*\\/\\s*limit|contextLimit/`. The `contextLimit` alternative matches the bare variable declaration on line 483, so the test stays green even if `ratio` is changed to a constant (e.g. `ratio: 0`).\n- `test("context.limit is sourced from Provider.getModel context limit")` (line 57) uses `/Provider\\.getModel|limit\\.context|contextLimit/` — any one of those tokens anywhere in the file passes; it does not verify the value is actually wired into `context.limit`.\n\nThese give a false sense of coverage: a refactor that renames a variable or removes the real computation but leaves a stray token would not be caught. Prefer asserting against actual emitted JSON (e.g. stub `Provider.getModel` and capture `process.stdout` writes from `emit("message_complete", …)`) so the 5-way `tokens` and `context` shapes and the `used = input + cache.read` / `ratio = used/limit` computations are verified at runtime.

Fix the following code review findings on aictrl-dev/cli PR #87 (head branch).
Run the relevant tests/linters after each change.

1. EVENTS.md:91 — Example ratio 0.049 ≠ emitted 0.04912
   Detail: The `message_complete` example shows `"context": { "used": 9824, "limit": 200000, "ratio": 0.049 }`, but `buildContextWindow` emits the unrounded float: `9824 / 200000 = 0.04912`. The example rounds to 3 decimals, which may mislead consumers who treat the doc as a byte-exact spec. Either note that `ratio` is an unrounded float, or pick an example whose `used/limit` is exact (e.g. used 9800 → 0.049).
2. packages/cli/src/cli/cmd/run.ts:88 — JSDoc hardcodes provider.ts:929 (line rot)
   Detail: The `buildContextWindow` JSDoc references `` `context: 0` (provider.ts:929) ``. A hardcoded file:line citation will silently rot the moment `provider.ts` is edited, turning the comment into misleading guidance. Reference the behavior/symbol (e.g. "the provider's default `limit.context = 0` for unregistered custom models") instead of a line number.
3. packages/cli/src/cli/cmd/run.ts:102 — ratio unclamped but documented as 0–1
   Detail: `buildContextWindow` computes `ratio: contextUsed / contextLimit` with no clamp, but EVENTS.md documents `ratio` as `(0–1)`. The code can legitimately produce `ratio > 1`: if `contextUsed` ever exceeds the registry limit (stale/lowered `model.limit.context` after a model update, or a provider whose actual billed prompt exceeds the registered window), `ratio` exceeds 1 and contradicts the documented range. Consumers relying on `0 ≤ ratio ≤ 1` (e.g. for a utilization bar) will break. Either clamp (`Math.min(1, used/limit)`) or relax the doc to note values may exceed 1 when usage exceeds the registered limit.
   Suggested fix: In buildContextWindow: `ratio: Math.min(1, contextUsed / contextLimit),` — or update EVENTS.md from "ratio (0–1)" to "ratio (0–1; may exceed 1 if usage exceeds the registered limit)".
4. packages/cli/src/cli/cmd/run.ts:509 — .catch(()=>null) swallows non-not-found errors
   Detail: `Provider.getModel(...).catch(() => null)` turns *every* rejection into the "unknown context" sentinel — not only the intended "model not registered" case. A transient registry fetch failure, a programming error in `getModel`, or a malformed `m.limit` shape would all silently degrade `message_complete.context` to `null` with zero signal, making regressions invisible. Consider catching only the expected not-found error type, or logging the unexpected error before falling back to `null`.
5. packages/cli/src/cli/cmd/run.ts:510 — Verify upstream tokens shape for all providers
   Detail: The correctness of both `context.used` and the `reasoning` field hinges on the upstream `info.tokens` shape that this diff cannot show:
1. `contextUsed = tokens.input + tokens.cache.read` is correct only if `input` EXCLUDES cached tokens (Anthropic semantics). For OpenAI, raw `prompt_tokens` historically INCLUDES cached tokens — if the upstream `LLM.Usage` isn't normalized per-provider, `used` double-counts cache reads, and the EVENTS.md "a token is counted in exactly one bucket" guarantee silently fails for those providers.
2. `reasoning: info.tokens.reasoning` emits `undefined` (dropped by JSON.stringify → missing field) if any provider's `StepFinishPart` doesn't populate `reasoning`.
Please confirm the upstream normalization covers every provider before relying on these metrics; otherwise guard with `(info.tokens.reasoning ?? 0)` and verify `input` excludes cache for OpenAI.
6. packages/cli/test/cli/usage-token-breakdown.test.ts:217 — Source-substring tests are brittle
   Detail: The "emit block shape" describe block reads `run.ts` as raw text and asserts on substrings (`"reasoning"`, `"cache"`, `"buildContextWindow"`, `"context"`). These assert on source *text*, not behavior: a rename/reformat breaks the test while behavior is unchanged (false negative), and a coincidental substring elsewhere in the 1500/500-char window could falsely pass (false positive). Prefer capturing the actual emitted event in a small integration test, or at least tighten the window to the exact emit object literal.

Fix the following code review findings on aictrl-dev/cli PR #87 (head branch).
Run the relevant tests/linters after each change.

1. packages/cli/src/cli/cmd/run.ts:514 — context.used excludes cache.write tokens
   Detail: `context.used` is computed as `tokens.input + tokens.cache.read`, which omits `cache.write` tokens. Per the EVENTS.md definition, `used` is "tokens occupying the model's context window this turn," but cache.write (cache-creation) tokens ARE part of the prompt sent to the model and DO occupy the context window — they're just billed at the cache-write rate instead of the standard rate. The total prompt occupying the context window is `input + cache.read + cache.write`.

This undercounts utilization most on the first turn of a conversation, where a large prefix is being written to the cache (large `cache.write`, small/zero `cache.read`). Since the entire purpose of this field is to "signal context-exhaustion risk" (ratio approaching/exceeding 1), undercounting `used` delays that signal. The EVENTS.md example illustrates the gap: input=1024, cache.read=8800, cache.write=1024 → reported `used`=9824, but actual prompt size is 10848.

Fix: `const contextUsed = tokens.input + tokens.cache.read + tokens.cache.write` and update the EVENTS.md definition of `used` to `input + cache.read + cache.write`.
   Suggested fix: Include cache.write in the sum: `const contextUsed = tokens.input + tokens.cache.read + tokens.cache.write`, and update EVENTS.md so `used` is documented as `input + cache.read + cache.write` (total prompt tokens).
2. packages/cli/test/cli/usage-token-breakdown.test.ts:96-120 — Tests assert on source text, not behavior
   Detail: The "message_complete emit block shape" describe block reads `run.ts` from disk and asserts that substrings ("reasoning", "buildContextWindow", "context", "cost:") appear near the `emit("message_complete")` call site. These are source-text checks, not behavioral tests:

1. They give false confidence — they pass even if `buildContextWindow`'s result is never wired into the emitted object, or if `info.tokens.reasoning` is `undefined` at runtime (which would make the emitted JSON drop the field, breaking the documented "0 when thinking is off" contract).
2. They're brittle — renaming a variable or extracting the emit into a helper breaks them with no real regression.
3. The actual emit path (token projection, `contextUsed = input + cache.read`, the `Provider.getModel` catch) has no behavioral coverage; the `buildContextWindow` unit tests only cover the pure helper with pre-computed inputs.

Consider a behavioral test that drives the real emit path with a stubbed `Provider.getModel` and a fake `info`, then asserts the exact emitted `message_complete` payload shape (including that `reasoning` is a real number).
   Suggested fix: Replace the source-text assertions with a behavioral test: invoke the real emit path with a mocked `Provider.getModel` (resolve a known limit) and a fake `info.tokens`, then assert the emitted `message_complete` object equals the expected 5-way tokens + context shape. This also covers the `contextUsed` arithmetic and the reasoning/cache wiring that are currently unverified.

Fix the following code review findings on aictrl-dev/cli PR #87 (head branch).
Run the relevant tests/linters after each change.

1. packages/cli/src/cli/cmd/run.ts:497 — reasoning may emit undefined, silently dropped
   Detail: The constructed `tokens` object copies `info.tokens.reasoning` (and the cache fields) verbatim. `JSON.stringify` silently omits `undefined` values, so if the upstream `StepFinishPart` accumulation leaves `reasoning` unset for non-thinking models, the emitted payload will lack a `reasoning` field entirely rather than emitting `0` — violating EVENTS.md's contract ("reasoning (number) ... 0 when thinking is off"). The same applies to `cache.read`/`cache.write` if those are optional on the type. Worth verifying the `info.tokens` shape; a defensive default (`reasoning: info.tokens.reasoning ?? 0`, and likewise for cache.read/cache.write) guarantees the documented schema is always emitted.
   Suggested fix: Default each field to 0 so the documented schema is always present:

const tokens = {
  input: info.tokens.input ?? 0,
  output: info.tokens.output ?? 0,
  reasoning: info.tokens.reasoning ?? 0,
  cache: {
    read: info.tokens.cache.read ?? 0,
    write: info.tokens.cache.write ?? 0,
  },
}
2. packages/cli/test/cli/usage-token-breakdown.test.ts:149-159 — Source-text substring tests give false confidence
   Detail: The `describe("message_complete emit block shape (source-verified, #86)")` block (and the adjacent source-reading tests) load `run.ts`/`EVENTS.md` as raw strings and assert substring presence inside arbitrary byte windows (e.g. `source.slice(emitIdx - 1500, emitIdx + 200)`). These do not exercise the emit path and give false confidence: they pass if `reasoning`/`buildContextWindow`/`cache.write` appear only in comments, and they will break on harmless refactors (field reordering, comment edits) while never actually validating the arithmetic. The `contextUsed includes cache.write` test only checks that the substring "cache.write" occurs on that line — it does not validate the sum, so an incorrect rewrite would still pass. Consider replacing these with a behavioral test that stubs `Provider.getModel`, captures the `emit("message_complete", …)` payload, and asserts the structured `tokens`/`context` object (or drop them and rely on the solid `buildContextWindow` unit tests above).